Welcome to File Toolkit for 4D®, an extension package for those of you who are serious about handling Finder objects within 4D applications.
After reading this short manual and trying the package, please do register your copy : for a low $99, you'll get rid of the welcome screen and get a full Acrobat™ documentation with hypertext links and code examples. You may reach us at ftk@dig.cie.fr for technical information or sales@dig.cie.fr for any commercial questions.
Clic the “Order Form (US)” button on the welcome screen and you will be asked for basic informations needed to register your copy, then print or save the order form and send it to :
Due to SimpleText restrictions, this short manual is divided into 2 parts.
Topics of FTk Short Manual 1/2 :
Conventions
Installing File Toolkit for 4D®
Protection and demo version
How to serialize your copy
Operation
Package structure
Tools set
FSSpec set
Finder set
File Info set
Topics of FTk Short Manual 2/2 :
Conventions
Folders set
Volumes set
Aliases set
Standard File set
File I/O set
Encapsulation set
Applications set
Progress bars set
Error codes
Conventions
Use SimpleText or any other text editor with style viewing features to read and print this document. All typographic enhancements will be lost otherwise, resulting in a less readable text.
Parameters parsing conventions :
fi 4D to File Toolkit for 4D®
‹ File Toolkit for 4D® to 4D
€ 4D to File Toolkit for 4D®, then modified by File Toolkit for 4D®
ø Result returned by File Toolkit for 4D® (0 or error code)
Functions description is set in Geneva 10. Functions syntax and code examples are set in Monaco 9. Parameter parsing directions (fi ‹ € ø) are set in Symbol 9. All are standard system fonts. If one of these fonts is missing from your system, the result may look a bit jagged.
Installing File Toolkit for 4D®
File Toolkit for 4D® is a 4th Dimension extension package. To include its functions to your current 4D application, drop the File Toolkit for 4D® file in the Mac4DX folder of your 4D structure folder. Create a new Mac4DX folder if none is present at installation.
Please note : File Toolkit for 4D® cannot be installed with External Mover Plus. File Toolkit for 4D® will only run under System 7.x and 4th Dimension® vs 3.2 (4D Server® 1.2) or above.
File Toolkit for 4D® is optimized for Power Macintosh®.
Protection and demo version
You may and should feel free to copy the demo version of File Toolkit for 4D® provided you include all the files of the original distribution archive.
While your copy of File Toolkit for 4D® is not registered, a welcome screen appears when you launch your 4D database application. This non serialized mode is the package's demonstration mode.
In demo mode, the package is fully functional, but the welcome screen will appear every hour, and you will have to wait longer and longer for the Ok button to activate...
No-hassle license : you only have to register one copy of File Toolkit for 4D® per developer, regardless of the number of machines or database applications you're working on.
You will be asked to enter the registration code for File Toolkit for 4D® for each one of your 4D structures. If you have registered your copy of File Toolkit for 4D® and then copy it to another database (i.e. an other Mac4DX folder) the package will then reverse to demo mode until you reenter your serial code.
How to serialize your copy
- When buying File Toolkit for 4D® from DIG, you receive a complete documentation and a license number.
- Launch your 4D database and click the Serialize button in the welcome screen.
- Enter your name, the name of your company and your license number as provided in the registration form.
- If the registration information is not valid, File Toolkit for 4D® will stay in demo mode.
Operation
File Toolkit for 4D® makes use of FSSpecs (File System Specifications) to reference Finder objects. A file, a folder, an alias, a volume, all these objects may be referenced by their FSSpec. Functions are provided in the FSSpec set for the purpose of converting pathnames to FSSpecs and back.
Using FSSpecs rather than pathnames offers several advantages :
- A FSSpec may refer to any object with a pathname longer than 255 characters.
- FSSpecs all have the same size (80 bytes) regardless of the location of the object referenced by the FSSpec.
- FSSpecs are the data structure internally used by the File Manager of the Mac operating system.
- Within File Toolkit for 4D®, FSSpecs are much faster than pathnames, for they don't have to be decoded.
- A pathname is only needed once at the start of a file operation, FSSpecs may be used afterwards.
FSSpecs are not persistent between two restarts of the computer. Neither are pathnames, if for example any part of the hierarchy is renamed or moved. When looking for persistence, try aliases, which may be handled through the package's alias set of functions.
For File Toolkit for 4D® (as for the File Manager in MacOS) a volume is a regular folder, all functions which work with FSSpecs to folders also work with FSSpecs to volumes.
Due to 4D operation, you may only parse 4D record fields from 4D to the package. If a package function returns a value, it must first be stored in a variable before being copied to a record field. This is the same for array elements.
OSErr values returned by most functions are either negative (File Manager system errors) or positive (File Toolkit for 4D® internal errors).
String parameters to functions may vary in length :
- 80 characters for FSSpecs.
- 32 characters for file and folder names.
- 4 characters for file signatures: types or creators.
Package structure
All of the package's functions are divided into several sets. Functions of the first two sets are often used in conjunction with functions of the remaining sets.
- Tools set : set and test package options, convert File Manager data to 4D types
- FSSpec set : FSSpecs to pathnames and back, direct FSSpec handling
- Finder set : perform usual Finder tricks
- File Info set : get to know and fix everything about file informations
- Folder set : manage folders every way you can
- Volume set : get a list of volumes, mount, unmount or eject them
- Alias set : create, store and resolve Finder aliases
- Standard file set : access the File Manager's standard open and save dialogs
- File I/O set : read and write bytes from selected files
- Encapsulation set : from whole files to 4D objects and back
- Application set : 3.. 2.. 1.. Launch !
- Progress bar set : show your progress in style
Tools set
Use calls to the Tools set of functions to fix the package options, and convert some data to types usable in 4D.
ft_IsSerialized (String ‹ Name ; String ‹ Company) ø Int Serialized
This function returns the operating status of File Toolkit for 4D®.
If Serialized = 1, the package was serialized, Name and Company hold the text entered in the registration dialog.
If Serialized # 1, the package is operating in demo mode.
ft_GetOptions (Int ‹ TraceOnError ; Int ‹ CopyBufferSize ; Int ‹ ProgressBar ; Int ‹ DeleteLocked ; Int ‹ inFrench)
This command gets the package operating options. Use it with ft_SetOptions to change a single option without affecting the others.
If TraceOnError = 1, and a function returns an error code different from noErr (0), 4D jumps into trace mode after the instruction line where the package was called (defaults to 0).
If CopyBufferSize # 0, a buffer of the specified size (in bytes) is allocated to the file copy functions.
If CopyBufferSize = 0, the default buffer of 256 Kb = 262144 bytes is used. To optimize performance, set the buffer size to a multiple of 512 bytes (262144 = 512*512).
If ProgressBar = 1, a progress bar window is displayed during long operations (file copy and delete). Defaults to 1.
If DeleteLocked = 1, locked files are trashed without returning an error code, similar to pressing the option key while emptying the trash. Defaults to 0.
If inFrench = 1, dialogs and error messages are displayed in French.
If inFrench = 0, dialogs and error messages are displayed in English.
ft_SetOptions (Int fi TraceOnError ; Int fi CopyBufferSize ; Int fi ProgressBar ; Int fi DeleteLocked ; Int fi inFrench)
This command sets the package operating options. Modifications are effective immediately. If an asynchronous file copy is in progress when the modification occurs, the current copy does not take the modification into account. inFrench is the only persistent option, all other options must be set at startup.
Refer to ft_GetOptions for a parameter description.
This command returns in the ErrorText string the description error number ErrorNum. Texts are only supplied for positive error codes (specific to File Toolkit for 4D®). System errors are not handled by ft_GetErrorText.
ft_BitTest (Long fi BitStream ; Int fi BitNum) ø Int BitState
BitState = 1 if bit BitNum is set to 1 in BitStream.
BitState = 0 if bit BitNum is set to 0 in BitStream.
Call this function when testing status bits in finderFlags (see ft_GetInfo).
ft_BitSet (Long fi BitStream ; Int fi BitNum ; Int fi BitState)
Sets bit BitNum to BitState (1 or 0) in BitStream.
Use this command to set status bits in finderFlags (see ft_SetInfo).
ft_Date2Long (Date fi theDate ; Time fi theTime) ø Long Secs
Converts theDate and theTime to a long integer (Secs) matching the number of past seconds since January 1st 1904. Call this function when setting the creation/modification/backup dates of a file/folder (see ft_SetInfo).
To work around the famous 4D time handling bug®, use it as shown below :
C_TIME (theTime)
C_DATE (theDate)
C_LONGINT (Secs)
Secs := ft_Date2Long (theDate; 0 + theTime)
ft_Long2Date (Long fi Secs ; Date ‹ theDate) ø Time theTime
Converts the number of seconds in Secs to theDate and theTime in 4D format.
Call this function when retrieving the creation/modification/backup dates of a file/folder (see ft_GetInfo).
To work around the famous 4D time handling bug®, use it as shown below :
Converts a full path name to a FSSpec. The pathname is not limited to 255 characters, allowing to parse a complex hierarchy exceeding this limit. If FullPath refers to a folder or volume, it must end with a colon character “:”.
FSSpec referencing non-existent files/folders allow you to create them : an error code (-43) is returned, yet the FSSpec is valid.
ft_FSSpec2Path (String fi TargetSpec ; Text ‹ FullPath) ø Int OSErr
Converts an FSSpec to a full pathname.
If TargetSpec refers to a folder or a volume, FullPath ends with a colon character “:”.
ParentSpec is a FSSpec referencing the parent folder of TargetSpec. For instance, if TargetSpec refers to "myHD:myFolder:myFolder2:", ParentSpec will refer to "myHD:myFolder:"
ft_FSSpecName (String fi TargetSpec ; String ‹ TargetName ; Int ‹ IsFolder) ø Int OSErr
Returns in TargetName the name of the object referenced by TargetSpec (file, folder, volume).
IsFolder = 1 if TargetSpec refers to a folder or volume.
For instance, if TargetSpec refers to "myHD:myFolder:myFolder2:", TargetName = "myFolder2" and IsFolder = 1.
ft_Add2FSSpec (String fi TargetSpec ; String fi Name ; String ‹ newSpec) ø Int OSErr
Adds a name to a folder FSSpec, to get a FSSpec referencing an item within the folder. TargetSpec must refer to a folder or volume. Name must be inserted between colons, (e.g. ":foo:") to add a folder to the TargetSpec FSSpec. A -43 error code is returned if Name does not exist, still newSpec is valid.
ft_SameFSSpec (String fi aSpec ; String ‹ anotherSpec ; Int ‹ sameFSSpec) ø Int OSErr
Compares two FSSpec. sameFSSpec = 1 if aSpec and anotherSpec both refer to the same object.
ft_GetFSSpeIcon (String fi TargetSpec ; Int fi LargeIcon ; Pict ‹ Icon) ø Int OSErr
Returns in Icon the finder icon of the object referenced by TargetSpec.
If LargeIcon = 1, the icon is a 32 x 32 bitmap (large icon).
If LargeIcon # 1, the icon is a 16 x 16 bitmap (small icon).
Finder set
Use calls to the Finder set to create, copy, move, delete and rename files and folders.
ft_Create (String € TargetSpec ; String fi Name ; String fi Type ; String fi Creator) ø Int OSErr
Creates a Name file using Type and Creator as signature in the folder referenced by TargetSpec.
If TargetSpec refers to a non-existent file, Name is ignored and TargetSpec is used for creation.
A FSSpec referencing the new file is returned in TargetSpec.
If a file already exists at this location, a -48 error code is returned.
Creates a Name folder in the folder referenced by TargetSpec.
If TargetSpec refers to a non-existent folder, Name is ignored and TargetSpec is used for creation.
A FSSpec referencing the new folder is returned in TargetSpec.
If a folder already exists at this location, a -48 error code is returned.
ft_Delete (String fi TargetSpec) ø Int OSErr
Deletes the object referenced by TargetSpec. If TargetSpec refers to a folder, its content is also deleted. If TargetSpec refers to an alias, the alias is deleted, but its target is left untouched.
If one of the deleted objects is locked, a -45 error code is returned, unless the DeleteLocked option is set in the package (see ft_SetOptions).
ft_AsyncDelete (String fi TargetSpec ; String fi ProcName ; Long ‹ ProcessID ; Long ‹ Refnum) ø Int OSErr
Deletes the object referenced by TargetSpec. If TargetSpec refers to a folder, its content is also deleted. If TargetSpec refers to an alias, the alias is deleted, but its target is left untouched.
Objects are deleted in the background, in a separate process, the id of which is returned in ProcessID. When the operation is completed, the ProcName command procedure is called by the ProcessID process. The ProcName procedure gets an OSErr integer parameter holding the operation error code, and a Refnum long integer that uniquely identifies the process where the delete action was performed.
Moves a file or a folder referenced by SourceSpec to the folder referenced by DestSpec on the same volume. Objects cannot be moved to a different volume, use ft_Copy and ft_Delete instead.
If NewName # "", the object is renamed after being moved. A -48 error code is returned if the object was moved but could not be renamed because NewName was already used by an other item in DestSpec.
Copies the object referenced by SourceSpec to the folder referenced by DestSpec with all its content.
DestSpec gets the new FSSpec to the copied object.
If NewName # "", the object is renamed after being copied.
If both the source and destination objects are located on the same AppleShare volume, copy is optimized so that the machine issuing the copy instruction is not used during transfer.
String fi ProcName ; Long ‹ ProcessID ; Long ‹ Refnum) ø Int OSErr
Copies the object referenced by SourceSpec to the folder referenced by DestSpec with all its content.
This function does not return a FSSpec to the copied object, use ft_FSSpecName and ft_Add2FSSpec instead.
If NewName # "", the object is renamed after being copied.
If both the source and destination objects are located on the same AppleShare volume, copy is optimized so that the machine issuing the copy instruction is not used during transfer.
Objects are copied in the background, in a separate process, the id of which is returned in ProcessID. When the operation is completed, the ProcName command procedure is called by the ProcessID process. The ProcName procedure gets an OSErr integer parameter holding the operation error code, and a Refnum long integer that uniquely identifies the process where the copy was performed.
Renames the object referenced by TargetSpec to NewName.
A FSSpec to the renamed object is returned in TargetSpec.
File Info set
Calls to the File Info set will let you handle all the information visible in the Informations option of the Finder's File menu.
ft_GetFileSign (String fi TargetSpec ; String ‹ Type ; String ‹ Creator) ø Int OSErr
Returns type and creator information for the file referenced by TargetSpec.
ft_SetFileSign (String fi TargetSpec ; String fi Type ; String fi Creator) ø Int OSErr
Sets type and creator information for the file referenced by TargetSpec.
If Type or Creator = "", the information is left untouched.
ft_GetInfo (String fi TargetSpec ; String ‹ FileType ; String ‹ FileCreator ; Long ‹ CreationDate ; Long ‹ ModifDate ; Long ‹ BackupDate ; Int ‹ FinderFlags ; Int ‹ Locked ; Long ‹ DataForkSize ; Long ‹ ResForkSize) ø Int OSErr
Returns finder informations for the file referenced by TargetSpec. For folder and volume information, see ft_FolderInfo and ft_GetVolInfo.
Locked = 1 if file is locked.
To convert dates and times to 4D format, use ft_Long2Date.
To test separate bits of FinderFlags, use ft_BitTest.
DataForkSize and ResForkSize are returned in bytes. Add them to get the total file size.
ft_SetInfo (String fi TargetSpec ; String fi FileType ; String fi FileCreator ; Long fi CreationDate ; Long fi ModifDate ; Long fi BackupDate ; Int fi FinderFlags ; Int fi Locked) ø Int OSErr
Sets finder informations for the file referenced by TargetSpec. To set folder and volume information, see ft_SetFolderInfo.
If Type or Creator = "", the information is left untouched.
Use the ft_Date2Long function to convert dates and times from 4D format.
Use the ft_BitSet function to set separate bits in FinderFlags.
ft_GetFileVers (String fi TargetSpec ; Int fi VersNum ; String ‹ LongStringVers ; String ‹ ShortStringVers ; Int ‹ CountryCode) ø Int OSErr
Gets informations for the VersNum ‘vers’ resource in the file referenced by TargetSpec. LongStringVers returns text, whereas ShortStringVers returns the short version number. CountryCode, well, is pretty obvious isn't it ? Use ResEdit to take a good look at a 'vers' resource before using this function.
ft_SetFileVers (String fi TargetSpec ; Int fi VersNum ; String fi LongStringVers ; String fi ShortStringVers ; Int fi CountryCode) ø Int OSErr
Sets informations for the VersNum ‘vers’ resource in the file referenced by TargetSpec, if it already holds one. ft_SetFileVers does not create a new ‘vers’ resource.
You may call ft_SetFileVers to modify the 'vers' resource of the current 4D structure file.
Modifications to other open 4D files (Proc.Ext, data files, files in the Mac4DX folder) may result in file corruption or system errors. The only safely modifiable active 4D document is the structure file.
See ft_GetFileVers for parameters list, and use ft_IsBusy to check a file prior to modification.
File Toolkit for 4D® is a trademark of DIG SARL.
4th Dimension and 4D Server are registered trademarks of ACI SA.
Acrobat, Apple, Macintosh, Power Macintosh, MacOS, Finder, AppleShare, Novell, Netware, PowerTalk are trademarks of their respective owners.
